JSON Instruction Node

The JSON Instruction node is a versatile component designed to help users build structured JSON payloads through an intuitive UI. This node lets you define named fields with specified data types and initial values, producing well-formed JSON objects that can be utilized by downstream nodes or external APIs for integration, automation, or data processing.

By structuring data explicitly, the JSON Instruction node reduces errors and ensures that communication between components or systems adheres to expected formats.

---

🔧 Configuration Panel Overview

Upon expanding the JSON Instruction node in your flow editor, the interface reveals:

• A header bar displaying the node label (default: “Json Instruction”), which you can rename for clarity.
• An editable row representing the first JSON field definition.
• Controls for managing fields:
  • Adding sibling fields directly below the current one.
  • Removing fields via a delete icon.
• The interface dynamically updates the resultant JSON object preview as you define fields.

This panel aims to simplify JSON construction without requiring manual text editing.

---

⚙️ Defining JSON Fields

Each editable row corresponds to a single key/value pair in the final JSON object. The configuration consists of multiple controls:

Control	Description
Name	The property name in the JSON object. Choose clear, meaningful names to describe the data. Conventionally use camelCase (userId) or snake_case (user_id).
Type	Defines the datatype of the field's value. Options include:
	- string: Textual data enclosed in quotes.
	- number: Numeric values including integers and floats.
	- boolean: Logical true or false values.
	- object: Nested JSON objects allowing complex hierarchical structures.
	- array: Collections of values or objects for list-like data.
Initial Value	Pre-populated content or a dynamic expression to initialize the field's value. The fx button lets you insert variables or flow expressions like {{userId}}.
Add Sibling (+)	Inserts a new JSON field immediately below the current one, allowing easy expansion of the object.
Delete (🗑)	Removes the current JSON field, updating the structure and removing the associated key/value pair.

---

Example of a JSON Field Row

Each row resembles the following structure:

├─ "initialNode"   \[ string  ]   \[ "start" ]   fx   \[+]   \[🗑]

• "initialNode" is the key name.
• [string] is the data type selector.
• [ "start" ] is the initial value.
• fx opens an expression builder for dynamic values.
• [+] adds a sibling field.
• [🗑] deletes the field.

---

📄 Resulting JSON Object

As you build the fields, the node generates a JSON object like:

{
  "initialNode": "start",
  "anotherKey": 123,
  "flag": true
}

This JSON can be passed to:

• LLM prompts that require structured context.
• Function calls in automation.
• API payloads where strict schema compliance is necessary.

---

🛠 Handling Complex JSON Structures

Nested Objects

• Use the object type to create nested key/value groups.
• When you select object, a new sub-panel or indented fields allow defining inner keys.
• This supports representing hierarchical data such as user profiles, configurations, or metadata.

Arrays

• The array type allows you to define lists of items.
• Arrays can hold primitives (strings, numbers, booleans) or complex objects.
• You can configure initial array values or expressions that resolve to arrays.

Dynamic Values via Expressions

• The fx button opens an expression editor.
• Use it to inject flow variables, e.g., {{user.id}}, or evaluate expressions like {{order.total * 1.1}}.
• This dynamic capability ensures JSON data reflects live or contextual information.

---

🚀 Best Practices

To create effective JSON payloads:

• Use Clear and Consistent Naming: Adopt naming conventions that match your backend or API expectations. This prevents integration errors.
• Validate Data Types: Ensure that your initial values and expressions produce values matching the selected types. Mismatches can break downstream logic.
• Leverage Dynamic Expressions: Use flow variables and computed expressions to keep JSON payloads relevant and current.
• Group Related Fields: Use sibling grouping to organize logically related keys together, enhancing readability and maintainability.
• Remove Unused Fields: Delete any placeholders or test fields to avoid sending extraneous data.
• Test Generated JSON: Always test the resulting JSON with target systems to confirm schema compatibility.

---

🧩 Example Setup

setup:
├─ "userId"      [ string  ]  [ "{{auth.userId}}" ]  fx  [+]
├─ "quantity"    [ number  ]  [ 1 ]
├─ "isActive"    [ boolean ]  [ true ]
├─ "profile"     [ object  ]
   ├─ "firstName" [ string  ]  [ "John" ]
   ├─ "lastName"  [ string  ]  [ "Doe" ]
├─ "items"       [ array   ]  [ [1, 2, 3] ]

This configuration produces:

{
  "userId": "abc123",
  "quantity": 1,
  "isActive": true,
  "profile": {
    "firstName": "John",
    "lastName": "Doe"
  },
  "items": [1, 2, 3]
}

---

📝 Practical Tips

• Start Small: Begin with simple JSON structures and incrementally add complexity.
• Keep Payloads Minimal: Avoid sending large unnecessary data; only include relevant fields.
• Document Your JSON Schema: Maintain documentation describing expected keys and types for collaboration.
• Use Validation Tools: Employ JSON schema validators to check correctness before deployment.
• Synchronize with Backend: Ensure your JSON keys and types match API or service expectations to prevent runtime errors.

---

⚠️ Common Pitfalls

• Type Mismatches: Defining a field as number but providing a string value causes errors.
• Missing Required Fields: Some downstream APIs require mandatory fields; ensure these are always present.
• Over-Nesting: Excessively deep nested objects can complicate parsing and debugging.
• Dynamic Expression Errors: Improper expressions (syntax errors or undefined variables) may result in empty or invalid values.
• Unused Fields: Leaving test or placeholder keys in production JSON can bloat payload size or cause unintended behavior.

---

Summary

The JSON Instruction node empowers users to create well-structured, typed JSON objects with ease, combining static values and dynamic expressions. Its intuitive interface reduces errors and enhances data flow integration across diverse AI workflows, APIs, and automation processes.

Proper use of naming conventions, typing, and dynamic value injection ensures your JSON payloads are robust, maintainable, and compatible with target systems.

---